18 January 2022

How to switch between Node.js versions with Homebrew

In this tutorial I'll show you the easiest way to switch between Node.js versions on macOS. To do so, we will use the Homebrew package manager and install and configure it.

Introduction

Homebrew is an awesome tool for installing and managing packages installed on macOS. It is also the best way to install Node.js and, with that, npm. But sometimes you'll need a different version of Node.js than the latest. In this tutorial I'll show you how to switch between multiple versions of Node.js on macOS with Homebrew.

First we need to make sure that your environment is ready. If you've not already done so, please make sure that Node.js is installed via Homebrew. First, check if Homebrew is installed with brew -v. If not, go to the the website brew.sh and copy-paste the command given in your terminal to install it. Test if Node.js is already installed somewhere else with node -v: if it gives you a version number, uninstall it by following these instructions. Now you're ready to install node via Homebrew: run brew install node. This installs the latest version of Node.js.

Installing older versions of Node.js

Now that you've got the latest version of Node.js installed, we'll also install the older versions of Node.js that you need. Do so for each major version by running the following command (replace 14 with a major version, like 13, 14 or 15).

brew install node@14

This installs the latest version of Node.js 14.

Switching between Node.js versions on macOS

So, how do we switch between Node.js versions on macOS? To do so, we'll add an alias to our .zshrc file. Running the following command will open up the nano text editor in the terminal:

nano ~/.zshrc

Now, paste the following code in the editor. Add a new line for each version of Node.js and replace node@16 with the correct major version.

alias node16='export PATH="/usr/local/bin:/usr/local/opt/node@16/bin:$PATH"; node -v'
alias node14='export PATH="/usr/local/opt/node@14/bin:$PATH"; node -v'

Why is the PATH for Node.js 16 different?

The reason has to do with npm. This comes bundled with Node.js. If you don't add this, npm will stay on the old version when you switch back to the latest version of Node.js.

Save the file with control + O and hit enter. Exit the editor with control + X.

Now the next time that you open up a new terminal, you can just type node14 to switch to Node.js 14 and node16 to switch back to version 16 (which is the latest version now). The nice thing here is, is that the switch only applies to one terminal session. Each time you open a new terminal window, you need to run this code again.

So if you want to work on an older version, run one of the specified commands. At the end of the terminal session, the 'environment' is destroyed, and you're always automatically using the latest version of Node.js unless you choose not to.

I'm using bash instead of zsh. What to do?

Running bash instead of zsh is no problem. Just put the above code in your .bashrc file instead of the .zshrc file.

Wrapping up

As you see, it's very easy to switch between Node.js versions on macOS by just using Homebrew. Homebrew has two advantages: it makes the managing of versions very easy ánd it allows you to easily work with multiple versions.

As a last tip, if you want to make an older version of Node.js the default, do the following:

brew unlink node
brew link --overwrite node@14

Thanks for taking the time to read this!

If you enjoyed it, and think others would benefit from the read then feel free to share it on Twitter (or elsewhere). I’m always up for a discussion about anything I’ve written too, so get in touch if you want to chat!

If you’ve spotted something out of place or something needs correcting, feel free to let me know.

This is the latest entry How to switch between Node.js versions with Homebrew

18 January 2022 In this tutorial I'll show you the easiest way to switch between Node.js versions on macOS. To do so, we will use the Homebrew package manager and install and configure it.

An older entry How to Install Node.js and NPM on Mac

8 January 2022 Install Node.js and NPM on Mac, using the Homebrew package manager. This simple tutorial walks you through all the necessary steps.